Typical HAL UART use cases for migration

This section provides information about typical HAL UART use cases for migration.

Note

The processes for transmitting and receiving data using polling, interrupt or DMA are the same in HAL1 and HAL2, except for the specification of buffer size: HAL1 uses Size for the number of data elements (u8 or u16), while HAL2 uses Size_byte for the buffer size in bytes.

Use case: UART communication in polling mode

Sequence diagram

UART processing in polling mode

@startuml participant "Application" as p1 participant "HAL UART driver" as p2 == initialization and configuration == == UART Processing in polling mode == alt polling p1->p2: HAL_UART_Transmit(&huart,\n aTxBuffer,\n DATA_TO_SEND_SIZE,\n 100) note over p2 #00FF00 Transmitting data ongoing end note p2-->p1: <color #Green> HAL_OK else p1->p2: HAL_UART_Receive(&huart,\n aRxBuffer,\n DATA_TO_RECEIVE_SIZE,\n 100) note over p2 #00FF00 Receiving data ongoing end note p2-->p1: <color #Green> HAL_OK end @enduml

Code snippet

HAL1

HAL2 

#define DATA_TO_SEND_SIZE           256
#define DATA_TO_RECEIVE_SIZE       DATA_TO_SEND_SIZE

uint8_t aTxBuffer[] = " **** UART Communication **** ";
uint8_t aRxBuffer[DATA_TO_RECEIVE_SIZE];

UART_HandleTypeDef huart;


HAL_UART_Init(&huart)




HAL_UART_Receive(&huart, aRxBuffer,
                      DATA_TO_RECEIVE_SIZE, 100)


HAL_UART_Transmit(&huart, aTxBuffer,
                      DATA_TO_SEND_SIZE, 100)

#define DATA_TO_SEND_SIZE           256
#define DATA_TO_RECEIVE_SIZE       DATA_TO_SEND_SIZE

uint8_t aTxBuffer[] = " **** UART Communication **** ";
uint8_t aRxBuffer[DATA_TO_RECEIVE_SIZE];

hal_uart_handle_t huart;
hal_uart_config_t uart_config;

HAL_UART_Init(&huart, HAL_UART4)

/* add config for uart instance */
HAL_UART_SetConfig(&huart, &uart_config)

HAL_UART_Receive(&huart, aRxBuffer,
                      DATA_TO_RECEIVE_SIZE, 100)


HAL_UART_Transmit(&huart,aTxBuffer,
                      DATA_TO_SEND_SIZE, 100)

Key changes

  1. In HAL2, the UART instance is provided to HAL_UART_Init() and configuration is separated using HAL_UART_SetConfig().

Use case: UART RX in interrupt mode

Sequence diagram

UART receive in interrupt mode

@startuml participant " Application" as p1 participant "HAL UART driver" as p2 participant "UARTX_IRQHandler" as p3 == initialization and configuration == == UART HAL Receive IT == p1->p2: <color: green> HAL_UART_Receive_IT(huart, aRxBuffer, DATA_TO_RECEIVE_SIZE) note over p2 #00FF00 Receiving data ongoing end note p2-->p1: HAL_OK p3<-: UARTX data interrupt p3->p2: HAL_UART_IRQHandler note over p2 #FFFF99 All data (Size == huart->RxXferCount) have been received end note note over p2 #00FF00 End of receiving data end note p2->p1: HAL_UART_RxCpltCallback(huart->RxXferCount) @enduml

Code snippet

HAL1

HAL2 

 #define DATA_TO_RECEIVE_SIZE       256

 uint8_t aRxBuffer[DATA_TO_RECEIVE_SIZE];

 UART_HandleTypeDef huart;


 /* Ensure that all required peripherals
   (USART, GPIO,NVIC etc.) are configured properly
 /*
 ...
 */

 /* UART register Receive complete user callback */
 HAL_UART_RegisterCallback(&huart, HAL_UART_RX_CB_ID,
                           UART_RxCpltCallback);

 /* Start a UART Process in interruption mode */
HAL_UART_Receive_IT(&huart, aRxBuffer,
                         DATA_TO_RECEIVE_SIZE)

#define DATA_TO_RECEIVE_SIZE       256

uint8_t aRxBuffer[DATA_TO_RECEIVE_SIZE];

hal_uart_handle_t huart;


/* Ensure that all required peripherals
  (USART, GPIO,NVIC etc.) are configured properly
/*
...
*/

/* UART register Receive complete user callback */
HAL_UART_RegisterRxCpltCallback(&huart, UART_RxCpltCallback);


/* Start a UART Process in interruption mode */
HAL_UART_Receive_IT(&huart, aRxBuffer,
                        DATA_TO_RECEIVE_SIZE)

Key changes

  1. HAL2 provides a dedicated registration API for RX completion callbacks: HAL_UART_RegisterRxCpltCallback().

  2. HAL2 RX completion callback includes an RX event argument (for example HAL_UART_RXEVENT_TC).

Use case: UART TX in interrupt mode

Sequence diagram

UART transmit in interrupt mode

@startuml participant " Application" as p1 participant "HAL UART driver" as p2 participant "UARTX_IRQHandler" as p3 == initialization and configuration == == UART HAL Transmit IT == p1->p2: <color: green> HAL_UART_Transmit_IT(&huart, aTxBuffer, DATA_TO_SEND_SIZE) note over p2 #00FF00 Transmitting data ongoing end note p2-->p1: HAL_OK p3<-: UARTX data interrupt p3->p2: HAL_UART_IRQHandler note over p2 #FFFF99 All data (Size == huart->TxXferCount) have been transmitted end note note over p2 #00FF00 End of transmitting data end note p2->p1: HAL_UART_TxCpltCallback(huart->TxXferCount) @enduml

Code snippet

HAL1

HAL2 

#define DATA_TO_SEND_SIZE       256

uint8_t aTxBuffer[DATA_TO_SEND_SIZE] = " **** UART Communication **** ";

UART_HandleTypeDef huart;


/* Ensure that all required peripherals
  (USART, GPIO,NVIC etc.) are configured properly
/*
...
*/

/* UART register Transmit complete user callback */
HAL_UART_RegisterCallback(&huart, HAL_UART_TX_CB_ID,
                          UART_TxCpltCallback);

/* Start a UART Process in interruption mode */
HAL_UART_Transmit_IT(&huart, aTxBuffer,
                        DATA_TO_SEND_SIZE)

#define DATA_TO_SEND_SIZE       256

uint8_t aTxBuffer[DATA_TO_SEND_SIZE] = " **** UART Communication **** ";

hal_uart_handle_t huart;

    /* Ensure that all required peripherals
      (USART, GPIO,NVIC etc.) are configured properly
    /*
    ...
    */

    /* UART register Transmit complete user callback */
    HAL_UART_RegisterTxCpltCallback(&huart, UART_TxCpltCallback);


    /* Start a UART Process in interruption mode */
   HAL_UART_Transmit_IT(&huart, aTxBuffer,
                            DATA_TO_SEND_SIZE)

Key changes

  1. HAL2 provides a dedicated registration API for TX completion callbacks: HAL_UART_RegisterTxCpltCallback()..

Related examples in HAL2

Example name

Brief

hal_uart_two_boards_com_it_controller

How to handle an infinite number of transmit-receive transactions between two boards based on the UART-bus protocol with the HAL API, in interrupt mode.

hal_uart_two_boards_com_it_responder

How to respond in an interrupt mode UART communication, driven by the controller, using the HAL API.

Use case: UART RX in DMA mode

Sequence diagram

UART receive in DMA mode

@startuml participant " Application" as p1 participant "HAL UART driver" as p2 participant "DMA" as p3 participant "DMAx_IRQHandler" as p4 == initialization and configuration == == UART HAL Receive DMA == p1->p2: <color: green> HAL_UART_Receive_DMA(&huart, aRxBuffer, DATA_TO_RECEIVE_SIZE) note over p2 #00FF00 Receiving data ongoing end note p2->p3: HAL_DMA_Start_IT() p3-->p2: HAL_OK p2-->p1: HAL_OK p4<-: DMAx complete interrupt p4->p3: HAL_DMA_IRQHandler note over p3 #00FF00 End of receiving data end note p3->p2: XferCpltCallback p2->p1: HAL_UART_RxCpltCallback(huart->rx_xfer_count) @enduml

Code snippet

HAL1

HAL2 

#define DATA_TO_RECEIVE_SIZE  255

UART_HandleTypeDef huart;

uint8_t aRxBuffer[DATA_TO_RECEIVE_SIZE];


/* Ensure that all required peripherals
(USART, GPIO,NVIC,DMA etc.) are configured properly
/*
...
*/

/* UART register Receive complete user callback */
HAL_UART_RegisterCallback(&huart, HAL_UART_RX_CB_ID,
                          UART_RxCpltCallback);

/* Start a UART Process in dma mode */
HAL_UART_Receive_DMA(&huart, aRxBuffer,
                             DATA_TO_RECEIVE_SIZE)

#define DATA_TO_RECEIVE_SIZE  255

UART_HandleTypeDef huart;

uint8_t aRxBuffer[DATA_TO_RECEIVE_SIZE];


/* Ensure that all required peripherals
  (UART, GPIO,NVI,DMA etc.) are configured properly
/*
...
*/

/* UART register Receive complete user callback */
HAL_UART_RegisterRxCpltCallback(&huart, UART_RxCpltCallback);


/* Start a UART Process in dma mode */
HAL_UART_Receive_DMA(&huart, aRxBuffer,
                         DATA_TO_RECEIVE_SIZE)

Key changes

  1. HAL2 DMA start uses HAL_DMA_StartPeriphXfer_IT_Opt() (optional interrupt generation) instead of HAL_DMA_Start_IT().

  2. HAL2 RX completion callback includes an RX event argument (for example HAL_UART_RXEVENT_TC).

Use case: UART TX in DMA mode

Sequence diagram

UART transmit in DMA mode

@startuml participant "User Application" as p1 participant "HAL UART driver" as p2 participant "UARTX_IRQHandler" as p5 participant "DMA" as p3 participant "DMAx_IRQHandler" as p4 == initialization and configuration == == UART HAL Transmit DMA == p1->p2: <color: green> HAL_UART_Transmit_DMA(&huart,aTxBuffer, DATA_TO_SEND_SIZE) note over p2 #00FF00 Transmitting data ongoing end note p2->p3: HAL_DMA_Start_IT() p3-->p2: HAL_OK p2-->p1: HAL_OK p4<-: DMAx complete interrupt p4->p3: HAL_DMA_IRQHandler note over p3 #00FF00 End of transmitting data end note p3->p2: XferCpltCallback p2->p2: Enable UARTx Transmit Complete IRQ (TCIE) p5<-: UARTx Transmit Complete (TCIE) p5->p2: HAL_UART_IRQHandler p2->p1: HAL_UART_TxCpltCallback(huart->TxXferCount) @enduml

Code snippet

HAL1

HAL2 

#define DATA_TO_SEND_SIZE  255

UART_HandleTypeDef huart;

uint8_t aTxBuffer[DATA_TO_SEND_SIZE] = " **** UART Communication **** ";


    /* Ensure that all required peripherals
      (USART, GPIO,NVIC,DMA etc.) are configured properly
    /*
    ...
    */

    /* UART register Transmit complete user callback */
    HAL_UART_RegisterCallback(&huart, HAL_UART_TX_CB_ID,
                              UART_TxCpltCallback);

    /* Start a UART Process in dma mode */
    HAL_UART_Transmit_DMA(&huart, aTxBuffer,
                              DATA_TO_SEND_SIZE)

#define DATA_TO_SEND_SIZE  255

hal_uart_handle_t huart;

uint8_t aTxBuffer[DATA_TO_SEND_SIZE] = " **** UART Communication **** ";


    /* Ensure that all required peripherals
      (USART, GPIO,NVIC,DMA etc.) are configured properly
    /*
    ...
    */

    /* UART register Transmit complete user callback */
    HAL_UART_RegisterTxCpltCallback(&huart, UART_TxCpltCallback);


    /* Start a UART Process in dma mode */
    HAL_UART_Transmit_DMA(&huart, aTxBuffer,
                              DATA_TO_SEND_SIZE)

Key changes

  1. HAL2 DMA start uses HAL_DMA_StartPeriphXfer_IT_Opt() (optional interrupt generation) instead of HAL_DMA_Start_IT().

  2. HAL2 uses byte-oriented transfer count fields (for example tx_xfer_count).

Related examples in HAL2

Example name

Brief

hal_uart_two_boards_com_dma_controller

How to handle an infinite number of transmit-receive transactions between two boards based on the UART-bus protocol with the HAL API, in DMA mode.

hal_uart_two_boards_com_dma_responder

How to respond in a dma mode UART communication, driven by the controller, using the HAL API.